<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="re-objects.html" />
<link rel="prev" href="matching-searching.html" />
<link rel="parent" href="module-re.html" />
<link rel="next" href="re-objects.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>4.2.3 Module Contents</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.2.2 matching vs Searching"
  href="matching-searching.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="4.2 re  "
  href="module-re.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="4.2.4 regular Expression Objects"
  href="re-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="matching-searching.html">4.2.2 Matching vs Searching</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-re.html">4.2 re  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="re-objects.html">4.2.4 Regular Expression Objects</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION006230000000000000000">
4.2.3 Module Contents</a>
</h2>
<a name="Contents_of_Module_re"></a>
<p>
The module defines several functions, constants, and an exception. Some of the
functions are simplified versions of the full featured methods for compiled
regular expressions.  Most non-trivial applications always use the compiled
form.

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-393' xml:id='l2h-393' class="function">compile</tt></b>(</nobr></td>
  <td><var>pattern</var><big>[</big><var>, flags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Compile a regular expression pattern into a regular expression
  object, which can be used for matching using its <tt class="function">match()</tt> and
  <tt class="function">search()</tt> methods, described below.

<p>
The expression's behaviour can be modified by specifying a
  <var>flags</var> value.  Values can be any of the following variables,
  combined using bitwise OR (the <code>|</code> operator).

<p>
The sequence

<p>
<div class="verbatim"><pre>
prog = re.compile(pat)
result = prog.match(str)
</pre></div>

<p>
is equivalent to

<p>
<div class="verbatim"><pre>
result = re.match(pat, str)
</pre></div>

<p>
but the version using <tt class="function">compile()</tt> is more efficient when the
expression will be used several times in a single program.
</dl>

<p>
<dl><dt><b><tt id='l2h-394' xml:id='l2h-394'>I</tt></b></dt>
<dd>
<dt><b><tt id='l2h-409' xml:id='l2h-409'>IGNORECASE</tt></b></dt><dd>
Perform case-insensitive matching; expressions like <tt class="regexp">[A-Z]</tt>
will match lowercase letters, too.  This is not affected by the
current locale.
</dd></dl>

<p>
<dl><dt><b><tt id='l2h-395' xml:id='l2h-395'>L</tt></b></dt>
<dd>
<dt><b><tt id='l2h-410' xml:id='l2h-410'>LOCALE</tt></b></dt><dd>
Make <tt class="regexp">\w</tt>, <tt class="regexp">\W</tt>, <tt class="regexp">\b</tt>, <tt class="regexp">\B</tt>,
<tt class="regexp">\s</tt> and <tt class="regexp">\S</tt> dependent on the current locale.
</dd></dl>

<p>
<dl><dt><b><tt id='l2h-396' xml:id='l2h-396'>M</tt></b></dt>
<dd>
<dt><b><tt id='l2h-411' xml:id='l2h-411'>MULTILINE</tt></b></dt><dd>
When specified, the pattern character "<tt class="character">^</tt>"
matches at the beginning of the string and at the beginning of each
line (immediately following each newline); and the pattern character
"<tt class="character">$</tt>" matches at the end of the string and at the end of each
line (immediately preceding each newline).  By default,
"<tt class="character">^</tt>" matches only at the beginning of the
string, and "<tt class="character">$</tt>" only at the end of the string and
immediately before the newline (if any) at the end of the string.
</dd></dl>

<p>
<dl><dt><b><tt id='l2h-397' xml:id='l2h-397'>S</tt></b></dt>
<dd>
<dt><b><tt id='l2h-412' xml:id='l2h-412'>DOTALL</tt></b></dt><dd>
Make the "<tt class="character">.</tt>" special character match any character at all,
including a newline; without this flag, "<tt class="character">.</tt>" will match
anything <em>except</em> a newline.
</dd></dl>

<p>
<dl><dt><b><tt id='l2h-398' xml:id='l2h-398'>U</tt></b></dt>
<dd>
<dt><b><tt id='l2h-413' xml:id='l2h-413'>UNICODE</tt></b></dt><dd>
Make <tt class="regexp">\w</tt>, <tt class="regexp">\W</tt>, <tt class="regexp">\b</tt>, <tt class="regexp">\B</tt>,
<tt class="regexp">\d</tt>, <tt class="regexp">\D</tt>, <tt class="regexp">\s</tt> and <tt class="regexp">\S</tt>
dependent on the Unicode character properties database.

<span class="versionnote">New in version 2.0.</span>

</dd></dl>

<p>
<dl><dt><b><tt id='l2h-399' xml:id='l2h-399'>X</tt></b></dt>
<dd>
<dt><b><tt id='l2h-414' xml:id='l2h-414'>VERBOSE</tt></b></dt><dd>
This flag allows you to write regular expressions that look nicer.
Whitespace within the pattern is ignored,
except when in a character class or preceded by an unescaped
backslash, and, when a line contains a "<tt class="character">#</tt>" neither in a
character class or preceded by an unescaped backslash, all characters
from the leftmost such "<tt class="character">#</tt>" through the end of the line are
ignored.
</dd></dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-400' xml:id='l2h-400' class="function">search</tt></b>(</nobr></td>
  <td><var>pattern, string</var><big>[</big><var>, flags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Scan through <var>string</var> looking for a location where the regular
  expression <var>pattern</var> produces a match, and return a
  corresponding <tt class="class">MatchObject</tt> instance.
  Return <code>None</code> if no
  position in the string matches the pattern; note that this is
  different from finding a zero-length match at some point in the string.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-401' xml:id='l2h-401' class="function">match</tt></b>(</nobr></td>
  <td><var>pattern, string</var><big>[</big><var>, flags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  If zero or more characters at the beginning of <var>string</var> match
  the regular expression <var>pattern</var>, return a corresponding
  <tt class="class">MatchObject</tt> instance.  Return <code>None</code> if the string does not
  match the pattern; note that this is different from a zero-length
  match.

<p>
<span class="note"><b class="label">Note:</b>
If you want to locate a match anywhere in
  <var>string</var>, use <tt class="method">search()</tt> instead.</span>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-402' xml:id='l2h-402' class="function">split</tt></b>(</nobr></td>
  <td><var>pattern, string</var><big>[</big><var>, maxsplit<code> = 0</code></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Split <var>string</var> by the occurrences of <var>pattern</var>.  If
  capturing parentheses are used in <var>pattern</var>, then the text of all
  groups in the pattern are also returned as part of the resulting list.
  If <var>maxsplit</var> is nonzero, at most <var>maxsplit</var> splits
  occur, and the remainder of the string is returned as the final
  element of the list.  (Incompatibility note: in the original Python
  1.5 release, <var>maxsplit</var> was ignored.  This has been fixed in
  later releases.)

<p>
<div class="verbatim"><pre>
&gt;&gt;&gt; re.split('\W+', 'Words, words, words.')
['Words', 'words', 'words', '']
&gt;&gt;&gt; re.split('(\W+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
&gt;&gt;&gt; re.split('\W+', 'Words, words, words.', 1)
['Words', 'words, words.']
</pre></div>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-403' xml:id='l2h-403' class="function">findall</tt></b>(</nobr></td>
  <td><var>pattern, string</var><big>[</big><var>, flags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Return a list of all non-overlapping matches of <var>pattern</var> in
  <var>string</var>.  If one or more groups are present in the pattern,
  return a list of groups; this will be a list of tuples if the
  pattern has more than one group.  Empty matches are included in the
  result unless they touch the beginning of another match.
  
<span class="versionnote">New in version 1.5.2.</span>

<span class="versionnote">Changed in version 2.4:
Added the optional flags argument.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-404' xml:id='l2h-404' class="function">finditer</tt></b>(</nobr></td>
  <td><var>pattern, string</var><big>[</big><var>, flags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Return an iterator over all non-overlapping matches for the RE
  <var>pattern</var> in <var>string</var>.  For each match, the iterator returns
  a match object.  Empty matches are included in the result unless they
  touch the beginning of another match.
  
<span class="versionnote">New in version 2.2.</span>

<span class="versionnote">Changed in version 2.4:
Added the optional flags argument.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-405' xml:id='l2h-405' class="function">sub</tt></b>(</nobr></td>
  <td><var>pattern, repl, string</var><big>[</big><var>, count</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Return the string obtained by replacing the leftmost non-overlapping
  occurrences of <var>pattern</var> in <var>string</var> by the replacement
  <var>repl</var>.  If the pattern isn't found, <var>string</var> is returned
  unchanged.  <var>repl</var> can be a string or a function; if it is a
  string, any backslash escapes in it are processed.  That is,
  "<tt class="samp">\n</tt>" is converted to a single newline character, "<tt class="samp">\r</tt>"  is converted to a linefeed, and so forth.  Unknown escapes such as
  "<tt class="samp">\j</tt>" are left alone.  Backreferences, such as "<tt class="samp">\6</tt>", are
  replaced with the substring matched by group 6 in the pattern.  For
  example:

<p>
<div class="verbatim"><pre>
&gt;&gt;&gt; re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',
...        r'static PyObject*\npy_\1(void)\n{',
...        'def myfunc():')
'static PyObject*\npy_myfunc(void)\n{'
</pre></div>

<p>
If <var>repl</var> is a function, it is called for every non-overlapping
  occurrence of <var>pattern</var>.  The function takes a single match
  object argument, and returns the replacement string.  For example:

<p>
<div class="verbatim"><pre>
&gt;&gt;&gt; def dashrepl(matchobj):
...     if matchobj.group(0) == '-': return ' '
...     else: return '-'
&gt;&gt;&gt; re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'
</pre></div>

<p>
The pattern may be a string or an RE object; if you need to specify
  regular expression flags, you must use a RE object, or use embedded
  modifiers in a pattern; for example, "<tt class="samp">sub("(?i)b+", "x", "bbbb
  BBBB")</tt>" returns <code>'x x'</code>.

<p>
The optional argument <var>count</var> is the maximum number of pattern
  occurrences to be replaced; <var>count</var> must be a non-negative
  integer.  If omitted or zero, all occurrences will be replaced.
  Empty matches for the pattern are replaced only when not adjacent to
  a previous match, so "<tt class="samp">sub('x*', '-', 'abc')</tt>" returns
  <code>'-a-b-c-'</code>.

<p>
In addition to character escapes and backreferences as described
  above, "<tt class="samp">\g&lt;name&gt;</tt>" will use the substring matched by the group
  named "<tt class="samp">name</tt>", as defined by the <tt class="regexp">(?P&lt;name&gt;...)</tt> syntax.
  "<tt class="samp">\g&lt;number&gt;</tt>" uses the corresponding group number;
  "<tt class="samp">\g&lt;2&gt;</tt>" is therefore equivalent to "<tt class="samp">\2</tt>", but isn't
  ambiguous in a replacement such as "<tt class="samp">\g&lt;2&gt;0</tt>".  "<tt class="samp">\20</tt>"  would be interpreted as a reference to group 20, not a reference to
  group 2 followed by the literal character "<tt class="character">0</tt>".  The
  backreference "<tt class="samp">\g&lt;0&gt;</tt>" substitutes in the entire substring
  matched by the RE.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-406' xml:id='l2h-406' class="function">subn</tt></b>(</nobr></td>
  <td><var>pattern, repl, string</var><big>[</big><var>, count</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Perform the same operation as <tt class="function">sub()</tt>, but return a tuple
  <code>(<var>new_string</var>, <var>number_of_subs_made</var>)</code>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-407' xml:id='l2h-407' class="function">escape</tt></b>(</nobr></td>
  <td><var>string</var>)</td></tr></table></dt>
<dd>
  Return <var>string</var> with all non-alphanumerics backslashed; this is
  useful if you want to match an arbitrary literal string that may have
  regular expression metacharacters in it.
</dl>

<p>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-408' xml:id='l2h-408' class="exception">error</tt></b></dt>
<dd>
  Exception raised when a string passed to one of the functions here
  is not a valid regular expression (for example, it might contain
  unmatched parentheses) or when some other error occurs during
  compilation or matching.  It is never an error if a string contains
  no match for a pattern.
</dd></dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.2.2 matching vs Searching"
  href="matching-searching.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="4.2 re  "
  href="module-re.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="4.2.4 regular Expression Objects"
  href="re-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="matching-searching.html">4.2.2 Matching vs Searching</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-re.html">4.2 re  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="re-objects.html">4.2.4 Regular Expression Objects</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
